Tutorial: Use JavaScript to control your application state

In this tutorial you learn how to set the state of your application using a JavaScript script. In the tutorial you create a fuel gauge, add a state manager which sets the gauge color, and use a JavaScript script to control the gauge state.

This video shows the result of the tutorial.

This tutorial assumes you understand the basics of working with Kanzi Studio. The best entry points for getting familiar with Kanzi Studio are:

Assets for the tutorial

The starting point of this tutorial is the Scripting states.kzproj Kanzi Studio project file stored in the <KanziWorkspace>/Tutorials/Scripting states/Assets directory.

The <KanziWorkspace>/Tutorials/Scripting states/Completed directory contains the completed Kanzi Studio project of this tutorial.

Create the fuel level indicator

In this section you create the fuel level indicator which displays the amount of fuel on the fuel gauge. You create the brushes that you use for the colors on the fuel level indicator. In the next section you create a state manager that sets a brush for each state.

To create the fuel level indicator for the fuel gauge:

  1. Open the starting point project located in the <KanziWorkspace>/Tutorials/Scripting states/Assets directory.
    The starting point project contains an Image node called FuelGauge, which sets the appearance of the fuel gauge.
  2. In the Project press Alt and right-click the FuelGauge node, select Empty Node 2D, and name it FuelLevel.
    You use the FuelLevel node to create the fuel level indicator for the gauge.
  3. In the Library press Alt and right-click Materials and Textures, select Color Brush, name it Full, and in the Properties set:You use this brush to set the color of the fuel gauge when it is full.

    TIP

    In Kanzi Studio you can apply color in hexadecimal format to all properties that set a color. In a tool that you use to set the color, copy the hexadecimal code of a color, in Kanzi Studio in the Properties right-click the color swatch of the property for which you want to use that color, and select Paste Color in Hex Format.

  4. Repeat the previous step twice to create two more color brushes, but name them Half and Empty, and in the Properties:You use these brushes to set the color of the fuel level indicator when it is half full or empty.

Define the states for the fuel indicator

In this section you create a state manager with states that set how the fuel indicator looks when the level of fuel is full, half full, and empty. To indicate the amount of fuel, in each of the states you use one of the color brushes you created in the previous section.

To define the states for the fuel indicator:

  1. In the Project select the RootPage > FuelGauge > FuelLevel node, in the State Tools click Create State Manager to create and add the state manager to the FuelLevel node.
  2. In the State Tools click Create State three times to create three states, and double-click the name of each state to rename them Full, Half, and Empty.
    You use each state to set the color of the fuel indicator when the application is in that state.
  3. In the Project select the FuelLevel node, in the Properties click next to the Background Brush property to add that property, set it to Full, and in the State Tools click in the Full state to set the value of the Background Brush property to that state.
    You set the fuel indicator color to green in the Full state.
  4. Repeat the previous step for the Half and Empty states, but set the Background Brush to the Half Color Brush in the Half state, and to the Empty Color Brush in the Empty state.
    You set the fuel indicator color to yellow in the Half state, and red in the Empty state.
    Kanzi sets the first state you create, in this case the Full state, as the initial state. The initial state is the state that Kanzi uses when the application first starts. In the State Tools the initial state has the icon.
    TIP

    You can set a state as the initial state by right-clicking the state and selecting Set as initial state in this group.

  5. In the State Tools click Edit State Manager to deactivate the State Tools.
    TIP

    When State Tools are switched on Kanzi Studio keeps track of all property changes in your project. For this reason it is a good practice to switch the State Tools off when you are done setting the states in a specific state manager.

  6. In the Project select the FuelLevel node, and in the Properties add and set:
    TIP

    To add a property, right-click in the Properties, select Add Property, and then select the property you want to add.
    For example, to add the Render Transformation property, right-click in the Properties, and select Add Property > Transform 2D > Render Transformation.

Create a slider to simulate the fuel level

In this section you create a slider, which you use to simulate the fuel level. You bind the Layout Height property of the FuelLevel node to the value of the slider so that when you move the slider knob, you change the height of the fuel level indicator.

To create a slider to simulate the fuel level:

  1. In the Assets window set Source to Factory Content.
    The Factory Content assets contain ready-made components which you can use to create prototype projects faster.
  2. From the Assets drag the Slider component, drop it in the Preview, in the Project select the Slider component, press F2, and rename it to Control.
    The Slider asset is a ready-made component, which you can use to create a slider which receives user input.
  3. In the Project select the Control slider, and in the Properties add and set:
  4. Control the fuel level indicator using the Slider component:
    1. In the Project press Alt and right-click the Control slider node, and select Alias.
      Kanzi Studio creates an alias pointing to the node from which you created the alias and adds it to the resource dictionary of its nearest ancestor node that contains a resource dictionary. Here you use the alias to access the Control slider when you bind the position of the slider to the height of the FuelLevel node.
      TIP

      You can see in the Dictionaries window the list of resources in the resource dictionaries that the node selected in the Project can access.

    2. In the Project select the FuelLevel node, and in the Properties click next to the Bindings to add a binding.
    3. In the Binding Argument Editor set:
      • Property to Layout Height
      • Expression to
        {#Control/RangeConcept.Value}
      Click Save.
      With this binding you bind the Value property of the Control slider component to the Layout Height property of the fuel level indicator.
      TIP

      You can retrieve alias target nodes with bindings, the Kanzi Engine API, or scripting using the hash sign (#) followed by the name of the alias, regardless of the node location in the project. For example, use #Control to access the Control slider node using its alias.

      TIP

      When you write expressions for bindings in the Binding Argument Editor, the fastest and most accurate way to add nodes and their properties to an expression is to drag them from the Properties to the Expression editor in the Binding Argument Editor.
      For example, to add the Value property of the Slider node, in the Project select the Slider node and from the Properties drag the Value property to the Expression field in the Binding Argument Editor.

In the Preview when you drag the slider knob, you change the value of the Layout Height property in the FuelLevel node. You set the height of the fuel level indicator based on the position of the slider knob.

Create a JavaScript script to control the state of the fuel gauge

In this section you create a JavaScript script to control the state of the fuel gauge. The script sets the application state to either Full, Half, or Empty every time you move the slider.

To create a JavaScript script to control the state of the fuel gauge:

  1. In the Project select the RootPage > FuelGauge > FuelLevel node, in the Node Components > Triggers section add an On Property Change trigger.
    Kanzi executes the On Property Change trigger when the set property value changes.
  2. In the Node Components in the On Property Change trigger click Trigger Settings, and in the Trigger Settings Editor set:

    Click Save.
    You set Kanzi to execute the On Property Change trigger when the value of the Layout Height property in the FuelLevel node changes.

  3. In the On Property Change trigger click the Add dropdown menu, and select the Execute Script action.
  4. In the Execute Script window select + Create Script to create a script.
  5. In the Script Editor enter this script and click Save.
    // Get the Layout Height property of the FuelLevel node.
var height = node.getProperty("Node.Height");

// Set the state to Empty if the Layout Height is less than or equals 60 pixels.
// Set the state to Half if the Layout Height is more than 60 but
// less than or equals 300 pixels.
// If the Layout Height is more than 300 pixels, set the state to Full.
if (height <= 60)
{
    node.goToState("StateGroup.Empty");
}
else if (height > 60 && height <= 300)
{
    node.goToState("StateGroup.Half");
}
else
{
    node.goToState("StateGroup.Full");
}

Kanzi executes the JavaScript script, which sets the application state to either Full, Half, or Empty every time you move the slider.

In the Preview when you drag the knob on the slider, the FuelLevel state changes based on the value of the Layout Height property of the FuelLevel node.
When the height of the FuelLevel node is:

What's next?

In this tutorial you learned how to use a JavaScript script to control the state of an application. Now you can:

See also

Using scripts

Using state managers

Tutorial: Use JavaScript to create a demo mode

Tutorial: Use state managers to control your application

Tutorial: Creating a slider

Using bindings

Open topic with navigation